<HTML>
 <HEAD>
  <TITLE>pymini ERS</TITLE>
 </HEAD>
 <BODY BGCOLOR="#FFFFFF">
 <font face="Arial">
<center>
  <h1>PyMini</h1>
  <h3>External Reference Specification (ERS)</h3>
 </center>

  <h2>Table of contents</h2>
<ul>
<li><a href="#intro">1 Introduction</a>
<ul>
<li><a href="#license">1.1 License</a>
</ul>
<li><a href="#solution">2 Solution</a>
<li><a href="#overview">3 Overview</a>
<li><a href="#configuration">4 Configuration File</a>
<ul>
<li><a href="#emc_section">4.1 EMC section</a>
<li><a href="#display_section">4.2 DISPLAY section</a>
<li><a href="#traj_section">4.3 TRAJ section</a>
<li><a href="#axis_section">4.4 AXIS section</a>
<li><a href="#task_section">4.5 TASK section</a>
</ul>
<li><a href="#build">5 Software Installation</a>
<ul>
<li><a href="#binaryWin">5.1 Windows Install</a>
<li><a href="#binaryLinux">5.2 Linux Install</a>
<li><a href="#binaryMac">5.3 Mac OSX Install</a>
</ul>
<li><a href="#power">6 Power Up</a>
<li><a href="#test">7 Testing</a>
<li><a href="#tuning">8 Tuning</a>
<li><a href="#switches">9 Limit Switches</a>
<li><a href="#python">10 Python Scripts</a>
<li><a href="#homing">11 Homing</a>
<li><a href="#db25">12 DB25 Connector</a>
<li><a href="#spec">13 Specifications</a>
</ul>

<H2><a name="intro"></a>1 Introduction</H2>
This document presents a description of how to use PyMini with the <i>rt-stepper</i> dongle. This description is intended to define what the product controls, human interface, and machine interface. 
<p>
This document is provided "AS IS" without warranties of any kind including warranties of merchantability, fitness for a particular purpose, or non-infringement of intellectual property.
<p>
The <i>rt-stepper</i> dongle is a USB-to-Parallel dongle designed specifically for CNC controllers. 
This dongle provides CNC parallel port support and real time stepper motor control.
Precise step/directon pulses are generated by the dongle. You can use this dongle to convert a parallel port CNC controller into a USB CNC controller.
<p>
PC software is used to drive the dongle over the USB bus. 
The <i>rt-stepper</i> software consists of two major compenents - PyMini and the rtstepperemc library. 
PyMini is the GUI that provides the user interface. The rtstepperemc library provides the gcode interperter, trajectory planner and dongle IO.
<p>
Since the dongle provides the real time step pulse generator no real time kernal is required. 
This allows PyMini to run on Linux, Mac or Windows. 
All software is available at the rtstepperemc project <a href="http://code.google.com/p/rtstepperemc">http://code.google.com/p/rtstepperemc</a>.

<H3><a name="license"></a>1.1 License</H3>
The <i>rt-stepper</i> software that runs on the PC is covered by the <a href="http://www.gnu.org/licenses/gpl-2.0.txt">GNU GPL 2.0 license</a>.
<p>
Simply stated the GNU GPL license does allow the following.

<ul>
<li> Use the <i>rt-stepper</i> software at no charge.
<li> Distribute verbatim copies of the software in source or binary form.
<li> Sell verbatim copies of the software for a media fee or sell support for the software.
</ul>
What this license does NOT allow you to do is make changes or add features to <i>rt-stepper</i> software and then sell a binary distribution without source code. You must provide source code for any changes, or additions to the software and all code must be provided under the GPL or LGPL as appropriate.

<H2><a name="solution"></a>2 Solution</H2>
<center>
<IMG SRC="dongle.jpg">
</center>

<H2><a name="overview"></a>3 Overview</H2>
The <i>rt-stepper</i> dongle's USB connector connects to the PC. 
The dongle's DB25 connector connects to the parallel port of the CNC controller. 
With the PyMini application a user can operate a CNC machine manually or run a gcode program.
<p>
PyMini is a powerful minimalist user interface written in python.
A user can write their own gcode program using their favorite text editor or run a CAM generated gcode program on PyMini.
You can verify the gcode program with or without the dongle connected and view the xyz paths executed on the backplot panel.
All PyMini communication to the dongle takes place through the rtstepperemc library.
<p>
The rtstepperemc library is based on the same gcode interpreter and trajectory planner from the EMC/LinuxCNC project at
<a href="http://www.linuxcnc.org">www.linuxcnc.org</a>. 
Both projects are separate software applications and the dongle will only run with the PyMini software.
<p>
There is only one process that runs on the PC - PyMini. 
PyMini generates the step pulses, but step timing is maintained by dongle thus eliminating the need for a real time kernel. 
PyMini coverts the gcode instructions into a series of step buffers. 
Each step buffer is sent over the USB bus to the dongle. 
The dongle then clocks each step byte out over the parallel port at precise step intervals. 
Each step byte drives the step/direction pins on the CNC controller parallel port. 
<p>
<center>
<IMG SRC="pymini_annotated.png">
</center>
<p>
See the "Gcode Overview" section at <a href="http://www.linuxcnc.org">www.linuxcnc.org</a> for gcode syntax.
Note, mcodes are handled differently in PyMini. Most mcodes are implemented via python plugin scripts.  
This means spindle, coolant and homing can be executed via custom python scripts.


<H2><a name="configuration"></a>4 Configuration File</H2>
A configuration file will be used to set PyMini runtime options. By default the rtstepper.ini file is used as the configuration file.
You can also specify a custom ini file on the PyMini command line.

<pre>
pymini -i rtstepper.ini
</pre>

<p>
The ini file is a simple ASCII text file that must be customized for each unique CNC controller. Use any text editor to customize the ini file. Multiple ini files can be used for different CNC controllers.
The ini file is divided into different sections and key/value pairs. Sections are defined by brackets "[ ]" and key/value pairs are defined by the "=" character. Comment lines start with the "#" character.
The rest of this section define some common configuration options and their default values. 
Generally only these options need to be modified by the user.
<p>
<H3><a name="emc_section"></a>4.1 EMC section</H3>
<pre>
[EMC]
MACHINE = PyMini (rtstepper.ini)
</pre>
Sets the title in the UI application. Useful for identifying what ini file is loaded.

<H3><a name="display_section"></a>4.2 DISPLAY section</H3>
<pre>
[DISPLAY]
MDI_LABEL_1 = MDI-1
MDI_CMD_1 = G1 X0 Y0 F6
AUTO_FILE = your_file.nc
INC_JOG = 0.2
ABS_JOG = 1.0
JOG_SPEED = 6
</pre>
MDI_LABEL_1 sets MDI button 1 label.
<p> 
MDI_CMD_1 sets MDI button 1 gcode command.
<p> 
PyMini has support for 4 MDI command buttons (MDI_LABEL_1 - MDI_LABEL_4, MDI_CMD_1 - MDI_CMD_4).
<p>
AUTO_FILE sets the default Auto gcode file.
<p>
INC_JOG sets the default incremental jog (mm or inch).
<p>
ABS_JOG sets the default absolute jog (mm or inch).
<p>
JOG_SPEED sets the default jog speed (mm/minute or inch/minute).

<H3><a name="traj_section"></a>4.3 TRAJ section</H3>
<pre>
[TRAJ]
LINEAR_UNITS =          inch
DEFAULT_VELOCITY =      0.2
MAX_VELOCITY =         400
DEFAULT_ACCELERATION =  200
MAX_ACCELERATION =      400
</pre>

LINEAR_UNITS sets the engineering units (inch or mm).
<p> 
The other parameters set the trajectory planner default velocity and acceleration in engineering units. 
In the above example this would be 0.2 inches/second or 12 inches/minute (12 = 0.2 * 60).
This sets the trajectory planner overall acceleration and velocity then each axis can be 
fine tuned individually in the AXIS section.

<H3><a name="axis_section"></a>4.4 AXIS section</H3>
<pre>
[AXIX_n]
MAX_VELOCITY = 0.15
BACKLASH = 0.0
INPUT_SCALE = 32000
STEP_PIN = 2
DIRECTION_PIN = 3
STEP_ACTIVE_HIGH = 0
DIRECTION_ACTIVE_HIGH = 0
</pre>

There is a AXIS section for each axis (AXIS_0 - AXIS_3). 
<p>
MAX_VELOCITY specifies the max velocity for this axis. In the example this would be 0.15 inches/second. 
<p>
BACKLASH is the amount of backlash or "play" in your XYZ lead screw. Start with zero then after tuning your CNC system, measure your backlash and enter the values here. Note, backlash compensation is a poor substitute for good lead screws. Excessive backlash can "throw" the table, causing inaccurate cuts and or broken tool.
<p>
INPUT_SCALE define the stepper motor steps/inch for this axis. This is a function of your motor, lead screw and CNC controller. Metric values can be used here instead of inch.
<p>
Here are some notes on how to calculate the INPUT_SCALE for a Sherline mill using the using a Xylotex 3-axis CNC controller and 269 oz.in steppers. 
<pre>
1.8 = degrees/step
360 / 1.8 = 200 steps/revolution
.050 = one revolution of the lead screw
200 / .050 = 4000 steps/inch full steps

Since the Xylotex CNC controller board is set to 1/8 stepping.

4000 * 8 = 32000 steps/inch = INPUT_SCALE
</pre>
<p>
STEP_PIN specifies the step pin on the DB25 connector for this axis.
<p>
DIRECTION_PIN specifies the direction pin on the DB25 connector for this axis.
<p>
STEP_ACTIVE_HIGH specifies the polarity of the step signal (0 = active_low, 1 = active_high).
<p>
DIRECTION_ACTIVE_HIGH specifies the polarity of the direction signal (0 = active_low, 1 = active_high).
<p>
The default values for step/direction pins will work for many commercial CNC controller boards. 
Note, the dongle supports 8 digital output signals on DB25 connector pins 2, 3, 4, 5, 6, 7, 8 and 9.
Your CNC controller MUST be built to use these pins, most commercial boards are. 
<p>

<H3><a name="task_section"></a>4.5 TASK section</H3>
<pre>
[TASK]
INPUT0_ABORT = 0
INPUT1_ABORT = 0
INPUT2_ABORT = 0
</pre>
Use the "INPUTx_ABORT" option to automatically trigger a un-synchronized estop. 
Any "INPUTx_ABORT" option can be used to enable a estop. 
Generally the input signals are used for limit switches.
See the <a href="#switches">Limit Switches</a> section for wiring details.
<p>
When "INPUTx_ABORT=0" the INPUTx signal is ignored. This is the default.
<p>
When "INPUTx_ABORT=1" an "active high" transition on the INPUTx pin will cause a un-synchronized estop.

<H2><a name="build"></a>5 Software Installation</H2>
The best way to install PyMini is with a pre-build binary package. 
Pre-build binary packages are available at  <a href="http://www.ecklersoft.com/download.shtml">www.ecklersoft.com/download</a>. 
Installing from source code is an option, but should only be attempted by an experienced programmer or administrator.
See the configure.ac file for notes about installing from source code.

<p>
<H3><a name="binaryWin"></a>5.1 Windows Install</a></H3>
For Windows 7 and Windows 8 use the following steps to install PyMini.
Windows does not come with python, so the python interpreter must be installed separately in order to run PyMini. 
All PyMini software is contained in a single zip file.
This zip file will unzip into a single directory and all software can be run from this directory.   
<ol>
<li> Download and run the MSI installer for python2.7 or python3.x at <a href="https://www.python.org/downloads/windows">www.python.org</a>.
</li>
<li> Download the latest pymini-xxx-winxx-freeze.zip file from <a href="http://www.ecklersoft.com/download.shtml">www.ecklersoft.com/download</a>.
</li>
<li> Unzip the zip file by right clicking on the zip file and follow the instructions.
</li>
<li> After the extraction is complete, goto the unzip directory.
</li>
<li> At this point you should be able to run "pymini.py" by double clicking on it. This should start PyMini application.
</li>
<li> With no dongle plugged in, PyMini should display the message "unable to find rtstepper dongle".
You can verify your gcode file without the dongle plugged in by pressing the Verify button. 
</li>
<li>Now it is time to install the rt-stepper USB driver. Plug-in a USB cable from the PC to the rt-stepper dongle. 
This may cause a pop up "Driver not found". We have to manually install the rt-stepper driver that is included in the unzip directory.
</li>
<li>Go to the Windows Device Manager and look for device entry "rt-stepper 1a". 
</li>
<li>Right click on "rt-stepper 1a" and select Update Driver Software.
</li>
<li>Click on the button to install driver manually.
</li>
<li>Click on the Browse button and select the unzip directory then Next.
</li>
<li>Ignore the following Windows warning about unknown driver and install anyway.
</li>
<li>Once the driver is installed you should get the a successful completion dialog.
</li>
<li> Disable any power save options that will cause the PC to shutdown during CNC operation.
</li>
<li> Now you can re-run step 5 and there should now be no "unable to fine rtstepper dongle" message.
</li>
<li> You are now ready to proceed with the <a href="#power">Power Up</a> section.
</li>
</ol>

<H3><a name="binaryLinux"></a>5.2 Linux Install</a></H3>
For Ubuntu use the following instructions to install PyMini. 
All PyMini software is contained in a single zip file. 
Since all major Linux distributions include python by default PyMini will use the default python interpreter.
This zip file will unzip into a single directory and all software can be run from this directory.   
<ol>
<li>PyMini requires the python module tkinter (python-tk). By default Ubuntu does not install python-tk. 
You can install it with the following command.
<pre>
apt-get install python-tk
</pre>
</li>
</li>
<li> Download the latest pymini-xxx-xxx-freeze.zip file from <a href="http://www.ecklersoft.com/download.shtml">www.ecklersoft.com/download</a>.
</li>
<li> Unzip the zip file.
</li>
<li> At this point you should be able to run "pymini.py" from the unzip directory. This should start the PyMini application.
</li>
<li> With no dongle plugged in, PyMini should have displayed the message "unable to find rtstepper dongle".
You can verify your gcode file without the dongle plugged in by pressing the Verify button. 
</li>
<li> In order set the dongle USB device permission, copy the following rules file from the zip directory into "/etc/udev/rules.d".
<pre>
cp 55-rt-stepper.rules /etc/udev/rules.d
</pre>
</li>
<li> Plug-in a USB cable from the PC to the rt-stepper dongle.
</li>
<li> Disable any power save options that will cause the PC to shutdown during CNC operation.
</li>
<li> Now you can run "pymini.py" and there should be no "unable to find rtstepper dongle" message.
</li>
<li> You are now ready to proceed with the <a href="#power">Power Up</a> section.
</li>
</ol>

<H3><a name="binaryMac"></a>5.3 Mac OSX Install</a></H3>
For Mac OSX use the following instructions to install PyMini.
All PyMini software is contained in a single application bundle. 
Since OSX comes with python installed by default PyMini will use the default python interpreter. 
The bundle was build on OSX 10.9 and should run on 10.9 and above.
<ol>
<li> Download the latest pymini-xxx-macosx-xxx-intel.dmg disk image from <a href="http://www.ecklersoft.com/download.shtml">www.ecklersoft.com/download</a>.
</li>
<li> Double clicking on the dmg file will automatically mount and popup the file folder screen. 
You can use the icons from the disk image or you can drag-and-drop them into a folder on your hard drive. 
In order to modify the rtstepper.ini file you must drag-and-drop all four icons into a folder on your hard drive.
</li>
<li> At this point you can run PyMini by clicking on the icon.
</li>
<li> With no dongle plugged in, PyMini should have displayed the message "unable to find rtstepper dongle".
You can verify your gcode file without the dongle plugged in by pressing the Verify button. 
</li>
<li> Plug-in a USB cable from the PC to the rt-stepper dongle.
</li>
<li> Disable any power save options that will cause the PC to shutdown during CNC operation.
</li>
<li> Now you can run PyMini and there should be no "unable to find rtstepper dongle" message.
</li>
<li> You are now ready to proceed with the <a href="#power">Power Up</a> section.
</li>
</ol>


<H2><a name="power"></a>6 Power Up</H2>

The <i>rt-stepper</i> dongle is powered from the USB bus on the PC, no external power supply is required. Since the CNC controller has a separate power supply the following power up sequence must be used.

<ol>
<li> Power up the PC.
<li> If not already connected, plug the dongle into the PC via the USB cable. 
<li> After the kernel enumerates the USB device check the dongle's green LED.
<pre>
The LED should be on solid (no blinking). 
</pre>
<li> Power up the CNC controller.
</ol>

Use the reverse order for the power down sequence. 

<H2><a name="test"></a>7 Testing</H2>

Before we can start CNC stepping the motors we must verify the USB subsystem with the <i>rt-test</i> program. <i>rt-test</i> is part of the PyMini package.
<p> 
<font color=red>IMPORT!! The <i>rt-test</i> program must be performed with no CNC controller connected to the dongle.</font>
<p>
<i>rt-test</i> will verify that your USB subsystem on your PC can drive the <i>rt-stepper</i> dongle. Run "rt-test" from the command line and
the following checks will be made.

<ol>
<li> USB device enumeration.
<li> Device permissions.
<li> Start a 65K byte bulk write transfer.
<li> Wait for transfer complete.
<li> Print pass or fail.
</ol>

Run <i>rt-test</i> several times, if <i>rt-test</i> passes every time proceed to the Tuning section.

<H2><a name="tuning"></a>8 Tuning</H2>

Note if your CNC system matches a pre-configured <i>rt-stepper</i> *.ini file, then this tuning procedure may not be
necessary. See the sample *.ini files at <a href="http://www.ecklersoft.com/download.shtml">www.ecklersoft.com/download</a>.
<p>
Before we can cut any real parts we must tune <i>rt-stepper</i> with the CNC system. 
At this point the INPUT_SCALE values, see the Configuration File section, should be correct for your CNC controller.
<p>
Since <i>rt-stepper</i> has it's own real-time clock, tuning is very simple. 
All we have to determine is the MAX_VELOCITY for each axis on the CNC system. Then update the ini file with the new values. 
<p>
The MAX_VELOCITY is the max speed the stepper motors can operate at. Stepper motors will go out of sync if they are accelerated or decelerated too suddenly. 
This is because the magnetic fields are advancing faster than the rotor can keep up. 
Once a motor is out of synchronization further CNC stepping is useless as the position of that axis has been lost. 
<p>
For tuning purposes the measured MAX_VELOCITY should be less than the current MAX_VELOCITY values in the ini file. The initial values in the default
ini file should be a good starting point for tuning.
<p>
The MAX_VELOCITY is a very important control variable and can be used for the following functions.
<ol>
<li> Set rapid limit in PyMini.
<li> Set the max feed rate in the gcode file.
</ol>

MAX_VELOCITY must be measured for each axis.
Here is the procedure for measuring each axis.
<ol>
<li> Run PyMini.
<li> Set the Speed parameter to 60 * MAX_VELOCITY in the ini file.
<li> Jog the axis 1 inch.
<li> If the motor chatters or does not move at all reduce the Speed parameter and repeat step 1.
<li> Measure the distance moved, if not 1 inch reduce Speed and repeat step 1.
<li> Done, the resulting Speed is your measured MAX_VELOCITY, set MAX_VELOCITY = (Speed / 60) in the ini file. 
</ol>

Generally the measured MAX_VELOCITY is a function of your CNC controller board and stepper motors not <i>rt-stepper</i>. If your measured MAX_VELOCITY is not acceptable try reducing your steps/inch on your controller board. If you change your steps/inch remember to change the INPUT_SCALE in the ini file.
<p> 
When tuning is complete you are ready to start cutting parts. 

<H2><a name="switches"></a>9 Limit Switches</H2>
Depending on the CNC system limit switches are optional. If exceeding the XYZ physical limits can cause physical damage to your CNC system then limit switches are NOT optional.
<p>
The <i>rt-stepper</i> dongle supports three "active high" input signals called INPUT0, INPUT1 and INPUT2. 
Although any of the three input signals can be used for limit switches, the following example uses INPUT0.  
INPUT0 signal is hard wired to the DB25 connector pin 10. 
Multiple switches are wired in-series as normally closed switches connected to CNC ground. 

<center>
<img src="input_pins.png">
</center>
<p>
This configuration frees up INPUT1-2 for other uses and provides simple in-series cable wiring. 
Note, "active high" digital input signals means broken wires will be detected immediately.
<p>
INPUT0-2 have a internal pull up resistors so no external power or pull up resistor is required. 
INPUT0-2 use a Schmitt Trigger input buffer for noise immunity, but care should still be taken with the switch wiring. Do NOT route switch wires near power wires.
<p>
INPUT0-2 can be used to signal an un-synchronized estop of the current CNC controller move. This functionality can be enabled via the ini file.
See the <a href="#task_section">"INPUTx_ABORT"</a> option in the Configuration File section. 
<p>
Note the "input0-2_abort" option has a small amount of software overhead so the abort sequence in not immediate. 
Depending on how fast your PC is, some extra steps may be executed after a switch has been tripped. 
The number of extra steps will be feed rate dependent. Switches should be chosen that can handle any extra steps without being damaged.

<H2><a name="python"></a>10 Python Scripts</H2>
With PyMini most mcodes are supported via python plugin scripts. 
PyMini and the python plugin scripts use the same python interpreter <a href="https://www.python.org">www.python.org</a>. 
Python is a simple programming language that allow users to make their own custom changes without having to recompile the software.
<p>
What can you do with python a script? Scripts can perform the same functions as PyMini plus additional IO using an Adruino Uno board. 
By using PyMini's Adruino Uno board support this includes spindle on/off and coolant on/off control.
<p>
Arduino board support requires the python module pyserial. Pyserial supports both python 2.7 and python 3.x. 
You can download pyserial at <a href="http://pyserial.sourceforge.net">pyserial.sourceforge.net</a> and install using the following command.
<pre>
python setup.py install (python2.7)
python3 setup.py install (python3.x)
</pre>
<p>
Python scripts that execute spindle and coolant mcodes are included with the rtstepperemc software.  
Here is the python script file for turning the spindle on.
<pre>
#
# m3.py - m3 mcode script turns spindle on clockwise.
# 
# inputs:
#  p_num = rpm   # S parameter (spindle speed)
#  q_num = n/a
#
# example:
#  m3 s250.0
#
import pyemc
import arduino

def run(dongle, p_num, q_num):
   #print dongle.get_version()

   if (not arduino.connected):
      return

   if (not arduino.inited):
      arduino.init()

   # Init data direction register for output.
   arduino.call_response("DOUT,0\r")

   # Set shield pin high.
   arduino.call_response("DSET,0\r")
</pre>
<p>
A similar python script file (plugin/m5.py) would turn the spindle off.

<H2><a name="homing"></a>11 Homing</H2>

Homing is a process that moves an axis to a known position. Usually this is done with limit switches or in some cases separate homing switches. 
Homing is especially useful when your CNC system has no dials on each axis. However, different machines have different requirements and homing can be quite complicated.
<p>
The rtstepperemc software supports homing with user-defined mcodes. User-defined mcodes are M100-199 and all user-defined mcodes are implemented via python scripts. 
Included with PyMini is an example python script file that implements the user-defined mcode M190 (plugin/m190.py).
This is simple script file will home a specified axis. The user will need to customize the script for their CNC application.
M190 can be executed as a MDI command or from a gcode file.

<pre>
M190 P0 Q0 (use INPUT0 for estop, home x-axis)
M190 P0 Q1 (use INPUT0 for estop, home y-axis)
M190 P0 Q2 (use INPUT0 for estop, home z-axis)
</pre>

<H2><a name="db25"></a>12 DB25 Connector</H2>
This figure shows the <i>rt-stepper</i> dongle DB25 connector pin out.
The 8 digital outputs are reserved for step/direction signals.
<p>
<center>
<img src="db25.png">
</center>
<p>
<H2><a name="spec"></a>13 Specifications</H2>
Step resolution: 46,875 hz<br> 
Standards: USB V1.1, USB V2.0 Compliant<br>
USB Speed: Full Speed (12 Mb/s)<br>
VID: 0x04d8<br>
PID: 0xff45<br> 
Power: Bus Power Only (~5v)<br>
Indicators: Power<br>
Overall Dimensions: 2.6 in.(L) x 2.35 in.(W) x 0.95 in.(H)<br>
Weight: 2.3 oz.
<hr>
<font size=2>
<center>
&#169 2009-2015 Eckler Software<br>
<IMG SRC="sig.png"><br>
Last updated April 15, 2015
</center>
</font>
</font>
 </BODY>
</HTML>
